Crate tokio_executor

Task execution related traits and utilities.

In the Tokio execution model, futures are lazy. When a future is created, no work is performed. In order for the work defined by the future to happen, the future must be submitted to an executor. A future that is submitted to an executor is called a “task”.

The executor is responsible for ensuring that Future::poll is called whenever the task is notified. Notification happens when the internal state of a task transitions from not ready to ready. For example, a socket might have received data and a call to read will now be able to succeed.

This crate provides traits and utilities that are necessary for building an executor, including:

• The Executor trait spawns future object onto an executor.

• The TypedExecutor trait spawns futures of a specific type onto an executor. This is used to be generic over executors that spawn futures that are either Send or !Send or implement executors that apply to specific futures.

• enter marks that the current thread is entering an execution context. This prevents a second executor from accidentally starting from within the context of one that is already running.

• DefaultExecutor spawns tasks onto the default executor for the current context.

• Park abstracts over blocking and unblocking the current thread.

Implementing an executor

Executors should always implement TypedExecutor. This usually is the bound that applications and libraries will use when generic over an executor. See the trait documentation for more details.

If the executor is able to spawn all futures that are Send, then the executor should also implement the Executor trait. This trait is rarely used directly by applications and libraries. Instead, tokio::spawn is configured to dispatch to type that implements Executor.

Re-exports

• pub use enter::exit;

Modules

• park
  Abstraction over blocking and unblocking the current thread.

Structs

• DefaultExecutor
  Executes futures on the default executor for the current execution context.
• DefaultGuard
  Ensures that the executor is removed from the thread-local context when leaving the scope. This handles cases that involve panicking.
• Enter
  Represents an executor context.
• EnterError
  An error returned by enter if an execution scope has already been entered.
• SpawnError
  Errors returned by Executor::spawn.

Traits

• Executor
  A value that executes futures.
• TypedExecutor
  A value that spawns futures of a specific type.

Functions

• enter
  Marks the current thread as being within the dynamic extent of an executor.
• set_default
  Sets executor as the default executor, returning a guard that unsets it when dropped.
• spawn
  Submits a future for execution on the default executor – usually a threadpool.
• with_default
  Set the default executor for the duration of the closure